home *** CD-ROM | disk | FTP | other *** search
/ Amiga Tools 5 / Amiga Tools 5.iso / grafik / converter / limbo4.0 / limbo.readme < prev    next >
Encoding:
Text File  |  1996-07-16  |  9.6 KB  |  293 lines
  1. Limbo(1)               Limbo Manual Page                Limbo(1)
  2.  
  3.  
  4. NAME  
  5.  
  6.     limbo - fast 2D/3D fractal image compression
  7.  
  8. SYNOPSIS
  9.  
  10.     limbo2d [-options] <command> <filename>
  11.     limbo3d [-options] <command> <filename>
  12.  
  13. DESCRIPTION
  14.  
  15.     Limbo is a  very  fast  fractal  image  object  encoder.  It
  16.     encodes  an  input  image  by approximating it with a set of
  17.     affine contractive mappings - the fractal code.
  18.  
  19.     The current version can briefly  be  summarized  with  these
  20.     features:
  21.  
  22.     Current features:
  23.  
  24.       o  Complete  very  fast encoding of images or sequences of
  25.          images.
  26.  
  27.       o  Full  storing,  retrieving  and decoding of the fractal
  28.          code in a general interchange format.
  29.  
  30.       o  A  special n-dimensional feature space search technique
  31.          to reduce the encoding time.
  32.  
  33.       o  Quadtree encoding using n-levels.
  34.  
  35.       o  Decode  expansion  at  any level (i.e.  2, 4, 8...times
  36.          original size).
  37.  
  38.  
  39.     Missing features:
  40.  
  41.       o Automatic entropy coding of file.
  42.  
  43.       o Better   handling   of    different   image  file-format
  44.         (currently only support PGM/PPM).
  45.  
  46.       o And: all the bug-fixing.
  47.  
  48.     Image input and output is in the PPM (color)  or  PGM  (grey
  49.     level)  format  (Jef  Poskanzers  bitmap format, email: jef@
  50.     well.sf.ca.us). The output from the encoder is in a  special
  51.     'limbo' fractal format (*.lmb).
  52.  
  53.  
  54. COMMANDS
  55.  
  56.     e  Encode an image object:
  57.  
  58.        This command takes an image object and encodes it.
  59.  
  60.     d  Decode an image object:
  61.  
  62.        The decoding of an image object is done by  iteration  on
  63.        the   fractal  affine  transformations  loaded  from  the
  64.        fractal code.
  65.  
  66.     v  View fractal code information:
  67.  
  68.        Displays information stored  in  the  fractal  code  like
  69.        compression  ratio, encoding signal-to-noise ratio (PSNR)
  70.        and encoding time.
  71.  
  72.     a  Analyze a fractal code:
  73.  
  74.        Produces specific  output  images  of  the  partitioning,
  75.        error  and  distribution  of  shade and edge blocks. Very
  76.        useful for evaluation the  performance  of  the  encoder.
  77.        This option is only implemented for the 2D encoding.
  78.       
  79.  
  80. OPTIONS
  81.  
  82.     -q Be quiet.
  83.  
  84.     -x<n>  Maximum x size of the input image object.      
  85.  
  86.     -y<n>  Maximum y size of the input image object.     
  87.  
  88.     -z<n>  Maximum depth of an image sequence.
  89.  
  90.     -ox<n> Offset on the x axis. Default value=0
  91.  
  92.     -oy<n> Offset on the y axis. Default value=0
  93.  
  94.     -b<n>  Smallest range block size.  Typical 4 for 2D encoding
  95.            and  3  for  3D  encoding.   2D  default  value=4, 3D
  96.            default value=2
  97.  
  98.     -d<n>  Domain slide step size.  With a small step the domain
  99.            pool  gets  large  and the image quality is generally
  100.            increased, but  at  the  expense of lower compression
  101.            ratio.  2D default value=8, 3D default value=4
  102.  
  103.     -m<n>  Minimum  numbers  of domain blocks to compare a range
  104.            block  to.   The  encoding  time  is increased with a
  105.            larger  minimum  number but the image quality is also
  106.            raised.  The compression ratio is not influenced (not
  107.            directly).  Default value=4
  108.  
  109.     -s<n>  Maximum  number  of  domain blocks to compare a range
  110.            block with.  Default value=10
  111.  
  112.     -f<n>  Numbers  of feature space dimensions to use.  Default
  113.            value=3
  114.  
  115.     -r<n>  The  resolution  of  the grid division of the feature
  116.            space.   A  finer division (higher -r<n>) will give a
  117.            faster  search  in the feature space but also consume
  118.            more memory.  Default value=1000
  119.  
  120.     -n<n>  The  level  number  of  the quadtree partitioning.  0
  121.            gives  no  partitioning,  1  a one level partitioning
  122.            etc. Default value=0
  123.  
  124.     -i<n>  Number of decode iterations.  Default value=6
  125.  
  126.     -l<n>  The expansion level for the decoding process. 0 yield
  127.            no  expansion,  1 the  doubling  of  the  image  etc.
  128.            Default value=0
  129.  
  130.     -Qa<n> The  number  of  bits  used  for storing the contrast
  131.            scale value - alpha.   Default value=4
  132.  
  133.     -Qd<n> The  number  of  bits  used for storing the luminance
  134.            shift value - delta.  Default value=6
  135.  
  136.     -Amax<f> Maximum value for the contrast scale.  Values above
  137.              1.0   may   give   an   unstable  system.   Allowed
  138.              range:[0.0;2.55].  Default value=1.0
  139.  
  140.     -Amin<f> Minimum  value  for  the  contrast  scale.  Default
  141.              value=0.4
  142.  
  143.     -Tm<n> The threshold value for the splitting of a main block
  144.            in  the quadtree partitioning to four sub blocks.  If
  145.            the total distortion (MSE) exceeds <n> then the block
  146.            is split.  Default value:100
  147.  
  148.     -Te<n> The  threshold  value for the classification of shade
  149.            and  edge  blocks.  Blocks with variance greater than
  150.            <n> are classified as edges.  Default value:50
  151.  
  152.     -Tp<n> The  threshold  for post  processing a block.  If the
  153.            encoding of an block does not yield an acceptable low
  154.            distortion (MSE) then the encoder has the possibility
  155.            to  go  out  and  look  for more domain blocks in the
  156.            feature  space.   This  is  some times necessary when
  157.            comparing  a  range  block  to a very small number of
  158.            domains.   Extra  search  is  done  if the distortion
  159.            (MSE)  exceeds  <n>.   Default value=-1 i.e.  no post
  160.            processing.
  161.  
  162.  
  163. EXAMPLES
  164.  
  165.     To encode the PGM image 'lenna' at offset (100,50) and  size
  166.     (50,70)  with a block size of four and step size two using a
  167.     two level  quad-tree  partitioning  and  minimum  three  and
  168.     maximum 9 domain blocks type:
  169.  
  170.     'limbo2d -ox100 -oy50 -x50 -y70 -b4 -d2 -n2 -m3 -s9 e lenna'
  171.  
  172.     To  decode  it  using  only  five iteration and producing an
  173.     image two times the original scale:
  174.  
  175.                      'limbo2d -i5 -l1 d lenna'
  176.  
  177.     To encode eight frames of the 'missa' sequence type:
  178.  
  179.                      'limbo3d -z8 e missa'
  180.  
  181.     And to decode it again:
  182.  
  183.                      'limbo3d d missa'
  184.  
  185.  
  186. FILE ORGANIZATION
  187.  
  188.     Limbo expect to find three special directories from the call
  189.     path:
  190.  
  191.     'OrgGfx'  = original  graphics  directory  with the original
  192.                 PPM/ PGM bitmaps to be encoded.
  193.  
  194.     'CmpGfx'  = compare graphics directory with all the decoded,
  195.                 analyzed and converted bitmaps.
  196.  
  197.     'FCCODES' = fractal  codes  directory  with the fractal code
  198.                 output produced from the encoding process.
  199.  
  200.  
  201. SOFTWARE PACKAGE
  202.  
  203.     The limbo software package is freely available at  anonymous
  204.     ftp  site  'vision.auc.dk'  in directory 'pub/Limbo'. Try to
  205.     download it from here - and mail  me  if  your  got  serious
  206.     problems  with  the  code  or  problems  related  to fractal
  207.     compression - I'll be pleased to help.
  208.  
  209.     Limbo is written in ANSI-C and runs on (almost) any machine.
  210.     It  is  reported  to  run  on  Sun Sparc Stations, HP Apollo
  211.     (400/900), Silicon Graphics (Indy/MIPS), i486 (PC-Linux) and
  212.     Amiga  (68000/68030).  What is needed to compile and run the
  213.     package is an ANSI compatible C compiler (i.e. NOT a PC!).
  214.  
  215.     The  name  'limbo'  is  defined  by (from The 'New Webster's
  216.     Dictionary')
  217.  
  218.     "Limbo (Limbou) n. 
  219.  
  220.     1:   a  dwelling  place on the borders of hell to which some
  221.     theolo  consign  souls  who  cannot  go to heaven through no
  222.     fault  of  their own, esp.  the souls of unbaptized children
  223.     or  the  souls  of  the  righteous  who died before Christ's
  224.     coming.
  225.  
  226.     2:   a  place  or  condition  in  which people or things lie
  227.     neglected or forgotten.
  228.  
  229.     3:   West  indian  dance  involving bending backward under a
  230.     gradually  lowered horizontal bar.  It is often performed in
  231.     competition  [fr.  L.  in limbo, on the border, fr.  limbus,
  232.     hem, border]."
  233.  
  234.     When you limbo an image object it it is send to some obscure
  235.     place  (a  binary  file called *.lmb) from which it only can
  236.     return with help of an un-'limbo' (decode) command.
  237.  
  238.  
  239. BUGS
  240.  
  241.     Many!
  242.  
  243.  
  244. DISCLAIMER OF WARRANTY
  245.  
  246.     This program may be freely copied  and  distributed  for  no
  247.     charge  providing  this header is included. The code may NOT
  248.     be sold  commercially  without  prior  permission  from  the
  249.     author.
  250.  
  251.     This program is distributed without any express  or  implied
  252.     warranties   whatsoever.   Because   of   the  diversity  of
  253.     conditions and hardware under  which  this  program  may  be
  254.     used,  no  warranty  of  fitness for a particular purpose is
  255.     offered. The user is advised to test the program  thoroughly
  256.     before  relying  on it. The user must assume the entire risk
  257.     of using the program.
  258.  
  259. REFERENCES
  260.  
  261.     The principles of fractal encoding was taken from the reward
  262.     winning article by A. E. Jaquin:
  263.  
  264.     Arnaud  E.  Jaquin,  "Fractal  image  coding:   A   review",
  265.     Proceedings of the IEEE, 81(10):1451-1465, October 1993.
  266.  
  267.     Also see the bibliography in the report "Fast Fractal  2D/3D
  268.     Image  Compression"  (supplied  in  the  file "ftp://vision.
  269.     auc.dk/pub/Limbo/Fast_Fractal_2D_3D_Image_Compression.ps.gz"
  270.     ).  A  good  website for checking out the development in the
  271.     fractal encoding area is Yval Fishers fractal homepage:
  272.  
  273.              "http://inls.ucsd.edu/Research/Fractals"
  274. AUTHOR
  275.  
  276.     The program was based on  a  version  developed  by  Carsten
  277.     Frigaard, Jess Gade, Thomas Therp Hemmingsen and Torben Sand
  278.     in 1993/94 on Aalborg University, Denmark.
  279.  
  280.     The current version was developed and programmed by  Carsten
  281.     Frigaard.
  282.  
  283.     Any  bug  reports,  comments,  criticisms,  etc.   is   very
  284.     welcomed. Send it to:
  285.  
  286.     E-Mail: Frigaard@dk-online.dk (may change)
  287.  
  288.     S-Mail: Carsten Frigaard
  289.             Vesterbro 127, 907
  290.             DK-9000 Aalborg
  291.             Denmark
  292.  
  293.